Clusters Feature Integration #2816

ayv8er · 2025-06-27T17:38:29Z

Description and Related Issue(s)

This PR introduces Clusters Universal Name Service integration into the Blockscout explorer. Clusters is a cross-chain identity service that allows users to track multiple wallets across various networks under a single unified name (like vitalik/ or foobar/).

This optional integration adds a new Clusters directory, Clusters leaderboard, individual cluster details page, and search capability. The feature follows established patterns for optional service and includes proper env handling.

Proposed Changes

Environment Variables:

Added two new environment variables:
- NEXT_PUBLIC_CLUSTERS_API_HOST - for Clusters API endpoint
- NEXT_PUBLIC_CLUSTERS_CDN_URL - for Clusters CDN assets
Updated environment preset files in configs/envs/.env.jest and configs/envs/.env.localhost
Added validation schema in deploy/tools/envs-validator/schema.ts
Updated Helm deployment values in review YAML templates - deploy/values/

Documentation and Configuration:

Added Clusters feature documentation to docs/ENVS.md
Updated Jest configuration jest.config.ts and added test mocks jest/mocks/ and jest/setupAfterEnv.ts

API Configuration and Types:

Added clustersApi configuration in configs/app/apis.ts with optional Clusters API integration
Created lib/api/services/clusters.ts for Clusters API service layer
Added Clusters feature configuration in configs/app/features/clusters.ts
Updated API resources and types in lib/api/resources.ts and lib/api/types.ts

TypeScript Types and Stubs:

Created TypeScript type definitions in types/api/clusters.ts
Added test stubs in stubs/clusters.ts
Updated search types in types/api/search.ts

Core Library and Utilities:

Added complete lib/clusters/ directory with utilities for action bar, page utils, and input detection
Created specialized hooks in lib/hooks/:
- useAddressClusters.ts - for address specific cluster data
- useClusterPagination.ts - for cluster pagination logic
- useClusterSearch.ts - for cluster search functionality
- useClustersData.ts - for main clusters data fetching
- useQueryParams.ts - for URL query parameter handling
Updated navigation in lib/hooks/useNavItems.tsx
Updated metadata and analytics mappings for cluster pages in lib/metadata/ and lib/mixpanel/

Testing and QA:

Added comprehensive test coverage for all new utilities and hooks:
- lib/clusters/ utilities - action bar, page utils, input detection
- All custom hooks - useAddressClusters, useClusterPagination, useClusterSearch, useClustersData
- Search integration - useSearchWithClusters
- UI components - ClustersEntity
Updated Jest configuration and added testing infrastructure
Added test mocks for Next.js routes, SVG imports, and React hooks

Pages and Routing:

Added pages/clusters/index.tsx - main clusters directory page
Added pages/clusters/[name].tsx - individual cluster details page
Created corresponding page components:
- ui/pages/Clusters.tsx - clusters directory page component
- ui/pages/Cluster.tsx - individual cluster page component
Updated Next.js routing types in nextjs/nextjs-routes.d.ts

UI Components:

Clusters Directory/Leaderboard - ui/clusters/:
- ClustersActionBar.tsx - search and filter controls
- ClustersDirectoryTable.tsx and ClustersDirectoryTableItem.tsx - directory views
- ClustersDirectoryListItem.tsx - directory list item
- ClustersLeaderboardTable.tsx and ClustersLeaderboardTableItem.tsx - leaderboard views
- ClustersLeaderboardListItem.tsx - leaderboard list items
Individual Cluster Details - ui/cluster/:
- ClusterDetails.tsx - main cluster detail component
Address Integration - ui/address/clusters/:
- AddressClusters.tsx - clusters tab for address pages
Shared Components:
- ui/shared/ClusterIcon.tsx - cluster icon component
- ui/shared/entities/clusters/ClustersEntity.tsx - cluster entity display

Search and Navigation Integration:

Added cluster search suggestions in ui/snippets/searchBar/SearchBarSuggest/SearchBarSuggestCluster.tsx
Created ui/snippets/searchBar/useSearchWithClusters.tsx
Updated search utilities in ui/shared/search/utils.ts
Updated navigation components in ui/snippets/navigation/NavLinkIcon.tsx
Updated search bar components: SearchBar.tsx, SearchBarInput.tsx, SearchBarSuggest.tsx, SearchBarSuggestItem.tsx

Assets and Icons:

Added icons/clusters.svg for cluster-specific logo use
Updated icon type definitions in public/icons/name.d.ts

Breaking or Incompatible Changes

None. This is an additive feature that introduces optional clusters functionality. Existing installations will continue to work unchanged, and the new feature can be optionally enabled by setting the NEXT_PUBLIC_CLUSTERS_API_HOST environment variable.

Additional Information

5 minute Loom video displaying the Clusters feature - https://www.loom.com/share/6278c920204249b398a6f227b1cb701d?sid=5b7d6a88-b13e-4002-8fab-0c531ac92090

Checklist for PR author

I have tested these changes locally.
I added tests to cover any new functionality, following this guide
Whenever I fix a bug, I include a regression test to ensure that the bug does not reappear silently.
If I have added, changed, renamed, or removed an environment variable
- I updated the list of environment variables in the documentation
- I made the necessary changes to the validator script according to the guide
- I added "ENVs" label to this pull request

…user is searching for a cluster name vs a evm address

tive chain count

…functionality

…nges

…component logic

h tests

…to account

s.isEnabled to top of the function and utilizes select function of useQuery in useAp iQuery

…ays false

…date imports and test

…n addressMetadataSchema sub-schema

ui/pages/Clusters.pw.tsx

ui/cluster/ClusterDetails.tsx

ui/shared/entities/clusters/ClustersEntity.tsx

ui/shared/entities/clusters/ClustersEntity.pw.tsx

ui/snippets/searchBar/useSearchWithClusters.tsx

ui/pages/Cluster.pw.tsx

…while keeping search optimization

…ra ui

… and updates vie wport to narrow test case

tom2drum

There are some minor comments left, mainly regarding files clean up.

tom2drum · 2025-07-15T13:36:07Z

ui/pages/Clusters.pw.tsx

+    test.use({ viewport: devices['iPhone 13 Pro'].viewport });
+
+    test('clusters directory with data @mobile', async({ render, mockApiResponse, mockAssetResponse }) => {


I believe you missed the "+" sign here, so the screenshot for the "mobile" project was not generated. I apologize if the usage of tags like "+@mobile" or "+@dark-mode" is unclear in our contribution guide. I will add some amendments to clarify this later.

Since the component has different views for desktop and mobile devices, let's remove the viewport setting and correct the tag name so that the screenshot will be generated for each device type.

I also noticed that there are some previously generated screenshots for this test suite stored in the repository. Could you please clean them up?

Clusters.pw.tsx_mobile_Clusters-Directory-Page-clusters-directory-empty-state-mobile-1.png
Clusters.pw.tsx_mobile_Clusters-Directory-Page-clusters-directory-with-data-mobile-1.png
Clusters.pw.tsx_mobile_Clusters-Directory-Page-loading-state-mobile-1.png

Suggested change

test.use({ viewport: devices['iPhone 13 Pro'].viewport });

test('clusters directory with data @mobile', async({ render, mockApiResponse, mockAssetResponse }) => {

test('clusters directory with data +@mobile', async({ render, mockApiResponse, mockAssetResponse }) => {

ui/shared/entities/clusters/ClustersEntity.tsx

ui/shared/entities/clusters/ClustersEntity.pw.tsx

ui/pages/Cluster.pw.tsx

ui/snippets/searchBar/useSearchWithClusters.tsx

…screenshots

…plicit viewport config, updates screenshots

ayv8er added 30 commits June 22, 2025 14:40

adds clusters api configs

09aff98

adds clusters api configs

18eeee5

adds api types

3e8c016

adds props routes and titles for cluster pages

073ff24

adds query param enum for clusters api

98c2ac4

adds clusters svg

ebc3b21

adds dynamic page routes

416e1ac

adds clusters entity ui in ui/shared/entities

489f650

adds functions to detect input type; will be used to check whether a …

3c78b55

…user is searching for a cluster name vs a evm address

adds stubs for loading skeleton view

bcc9f55

adds pagination hook

ba2481a

adds query param hooks for clusters trpc endpoints

6e82802

adds query param hooks for clusters trpc endpoints

e3176db

adds components that make up the /clusters ui

f51fb65

adds components for /cluster ui

7abf89a

adds clusters api endpoint to query by cluster id

283ca0a

implements call to cluster id endpoint to get ac

31d0ae5

tive chain count

adds clusters search types and in api category

7603627

creates clusters search hook and wraps useQuickSearchQuery hook

0f30607

replaces useQuickSearchQuery for useSearchWithClusters hook for both …

c5698ff

…functionality

add search suggestion ui

a2e02f1

adds optional chaining to handle react re-render when search type cha…

b75739b

…nges

adds cluster ui to ui/pages/address on address details

f50021c

prevents clicking on cluster suggestion if address is non EVM

912538f

adds util functions for testability along with tests, for action bar …

5c66c45

…component logic

refactor - extract clusters display logic wit

d74ebe0

h tests

refactor: extract page utilities from Clusters.tsx with tests

370a674

adds jest testing infra for react components

9a11dc3

adds hook testing coverage

265788d

adds component and integration tests

5176607

ayv8er added 16 commits July 3, 2025 12:32

moves useQueryParams hook to lib/router and updates imports and test …

8212d88

…to account

moves config.features.cluster

0c4fbb9

s.isEnabled to top of the function and utilizes select function of useQuery in useAp iQuery

removes unnecessary 3rd column and isContractVerified since it is alw…

861ac38

…ays false

checks clusters enable for placeholder

8111308

makes isClusterClickable condition more generic for future repurpose

ebcdc8e

splits isEvmAddress out to general purpose utility in lib/address, up…

7ad3305

…date imports and test

moves all cluster hooks and tests to lib/clusters folder

5582662

wraps action bar with standard button wrapper

0c4f0a0

makes nextjs-routes mock condition stricter

a63f526

removes NEXT_PUBLIC_METADATA_API_HOST from main schema as it is now i…

de99aa9

…n addressMetadataSchema sub-schema

adds mock clusters api data

d7960c9

adds pw tests for cluster detail page

b1956a3

adds pw tests for clusters directory page

321b12a

adds pw tests for clustersentity ui component

34e4d0f

adds mock envs for pw tests

88646c1

adds clusters api host and cdn url to env.pw

c668ad9

tom2drum requested changes Jul 11, 2025

View reviewed changes

ayv8er added 7 commits July 14, 2025 10:47

fixes resolve react-hooks/rules-of-hooks violation in cluster search …

93cec58

…while keeping search optimization

throws error instead of using app error component

7b76822

uses semantic token to reference color as per standard method in chak…

854441e

…ra ui

removes empty or loading state pw tests

3c8239f

pw tests - uses mockAssetResponse for icons, removes redundant tests,…

4fb6d7c

… and updates vie wport to narrow test case

migrates all clusters pw tests from page.route to mockApiResponse

f1763cd

updates docker generated pw screenshots

a928634

tom2drum requested changes Jul 15, 2025

View reviewed changes

ayv8er added 5 commits July 15, 2025 14:06

removes object cloning in useSearchWithClusters hook

f6acc6e

uses standardized chakra name for backgroundColor

a05e3bc

resolves Clusters.pw.tsx docker screen generation issues and updates …

99322ab

…screenshots

removes unneeded screenshots for Cluster.pw.tsx

30e6aac

standardizes mobile testing approach with +@mobile tag by removing ex…

29802b8

…plicit viewport config, updates screenshots

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clusters Feature Integration #2816

Clusters Feature Integration #2816

Uh oh!

ayv8er commented Jun 27, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tom2drum left a comment

Uh oh!

tom2drum Jul 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

		test.use({ viewport: devices['iPhone 13 Pro'].viewport });

		test('clusters directory with data @mobile', async({ render, mockApiResponse, mockAssetResponse }) => {

Clusters Feature Integration #2816

Are you sure you want to change the base?

Clusters Feature Integration #2816

Uh oh!

Conversation

ayv8er commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description and Related Issue(s)

Proposed Changes

Breaking or Incompatible Changes

Additional Information

Checklist for PR author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tom2drum left a comment

Choose a reason for hiding this comment

Uh oh!

tom2drum Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ayv8er commented Jun 27, 2025 •

edited

Loading